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Typical REST Versioning 


Some time T1 

Some time T2 

GET /server/1 

GET /server/1 

{ 

{ 

"server": { 

"server": { 

"id": 1, 

"id": 1, 

"name": "myserver", 

"name": "myserver", 

"ips": ["10.42.100.1"] 

"description": 

} 

"ips": ["10.42.100.1"] 

} 

} 


} 


j 


Generally accepted rules: 

• clients should not break on additional keys 

• adding new attributes is backwards compatible 

• there is only ever going to be one version publicly accessable* * 

• the API will never roll back once in production (i.e. description can't just disappear once it's out there) 
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Typical REST Versioning 


Some time T1 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"ips": ["10.42.100.1"] 

} 

} 


Some time T2 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"ips": ["10.42.100.1"] 

} 

} 


All works very well for single vendor services 

• Github 

• AWS 

• Meetup 

• etc 


@sdaCK 


Some time T3 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"tags": ["db", "ha"] 
"ips": ["10.42.100.1"] 

} 

} 







Typical REST Versioning 


Some time T1 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"ips": ["10.42.100.1"] 

} 

} 



Some time T2 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"ips": ["10.42.100.1"] 

} 

} 



Development Workflow 
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Some time T3 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"tags": ["db", "ha"], 
"ips": ["10.42.100.1"] 

} 

} 


push to prod 
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Upstream Versioning 



Upstream Development Workflow 

il*l"ii 

IMI 
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Upstream Code going into Clouds and Products 
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Upstream Releases 







Client Perspective 


Liberty 




Cloud Product A 


Mitaka 


Public Cloud B 


Liberty 


Public Cloud C 
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Upstream Releases 














Client Experiencing A -*• B -► C 


Cloud A 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"ips": ["10.42.100.1"] 

} 

} 


Cloud B 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"tags": ["db", "ha"], 
"ips": ["10.42.100.1"] 

} 

} 


Cloud C 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"ips": ["10.42.100.1"] 

} 

} 


Time's Arrow seems to go backwards. 

Software is made to work on Cloud A, points at Cloud B still works, Cloud C is missing parameters 
leading to possibly confusing late failures. 
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The Assumed Good Enough Rules 

don't account for a 

Different Team Developing the Software 
than Deploying it 
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Microve 


Client Experiencing A -*• B -► C 


2.25 

Cloud A 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"ips": ["10.42.100.1"] 

} 

} 


2.40 

Cloud B 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"description": 

"tags": ["db", "ha"], 
"ips": ["10.42.100.1"] 

} 

} 


Base 

Cloud C 
GET /server/1 

{ 

"server": { 

"id": 1, 

"name": "myserver", 
"ips": ["10.42.100.1"] 

} 

} 


Time's Arrow seems to go backwards. 

Software is made to work on Cloud A, points at Cloud B still works, Cloud C is missing parameters 
leading to possibly confusing late failures. 
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Client Experiencing A -*• B -► C 

At time T3 with Microversions 



Cloud A 

Cloud B 

Cloud C 


GET /server/1 

GET /server/1 


GET /server/1 


{ 

{ 


{ 


"server": { 

"server": { 


"server": { 

Base 

"id": 1, 

"id": 1, 


"id": 1, 


"name": "myserver", 

"name": "myserver", 


"name": "myserver", 


"ips": ["10.42.100.1"] 

"ips": ["10.42.100.1"] 


"ips": ["10.42.100.1"] 


} 

} 


} 

\ 

} 

} 


} 


f 

2.25 



Cloud A 
GET /server/1 

OpenStack-Version: compute 2.25 

{ 

"server": { 

"id": 1, 

"name": "myserver", 

"description": "great server", 
"ips": ["10.42.100.1"] 

} 


Cloud B 
GET /server/1 

OpenStack-Version: compute 2.25 

{ 

"server": { 

"id": 1, 

"name": "myserver", 

"description": "great server", 
"ips": ["10.42.100.1"] 

} 


Cloud C 
GET /server/1 

OpenStack-Version: compute 2.25 

Status: 400 
Version not found 
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REST API Microversions 

• Concept 

Inspired by HTTP Content negotiation 

Allow incremental feature roll out in API instead of waiting for major version bump 
Introduced in 2014 in OpenStack Nova / Ironic (expanded to 6 projects now) 

• Technical Details 

Discoverable in root version document 
An explicit version header on each request 
Global incrementing version for entire service 
Defaults to minimum value 
Services continue to support old versions 
Hard 400 fail if version not found 



Very long history of 
getting here available 
at bar later upon 
request 


• Blog writeup including personas - https://dague.net/api-mv 
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Questions for the Future 


• Raising minimum versions? 

• How much compat code do we need to 
keep? 

• Machine specifications? 


@sdague 


OpenStack Nova Compute: 

GET/ 


{ 

"versions": [ 

{ 

"id": "v2.0", 

"links": [ 

{ 

"href": "http://openstack.example.com/v2/", 
"rel": "self" 

} 

]. 

"status": "SUPPORTED", 

"version": 

"min_version": 

}, 

{ 

"id": "v2.1", 

"links": [ 

{ 

"href": "http://openstack.example.eom/v2.l/", 
"rel": "self" 

} 

]. 

"status": "CURRENT", 

"version": "2.53", 

"min_version": "2.1", 

} 


} 








OpenStack APIs vs OpenAPI 


• Many OpenStack APIs evolved around WADL 

• Attempt to retrofit OpenAPI definitions in 2015 to many core APIs, 2 key issues 

- Duplicate actions that don't map to Swagger/OpenAPI 

• POST /servers/{id}/action 
{"reboot":""} 

• POST /servers/{id}/action 
{"resize": {"flavor": "ml.large"}} 

- Micro versions also don't really fit 

• Could they? 


"'ll:! 1 
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Parting Thoughts 


THANKS! 


• There are specific challenges to Open Source network consumable services being 
deployed in multiple organizationally controlled clouds 

- Tooling today largely doesn't consider that 

• If we don't consider it, we make it harder to do non single vendor Open Source all the 
way to the edge 

- How do we prevent that? 


https://dague.ri et/ap i - m v 
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